Crate homedir

This crate exists to provide a portable method to get any user’s home directory. The API is rather simple: there are two main functions, home and my_home. The former can get the home directory of any user provided you have their username. The latter can get the home directory of the user executing this process.

If all that is necessary is the home directory of the user executing this process, then other crates may be better options, such as directories. As well, using the home directory to find the documents, downloads, pictures, etc. directories may not be accurate.

This crate aims to work on both Windows and Unix systems. However, Unix systems do not have a unified API. This crate may not work on Unix systems which do not have the getpwnam_r(3), getpwuid_r(3), and getuid(2) functions. This does not pose a problem on Linux and macOS. As well, Windows has its own set of issues. See for Windows users.

For Windows, the windows module contains the implementation details. For Linux, macOS, and other Unix systems, the unix module contains the implementation details.

Usage

This crate is on crates.io and can be used by executing cargo add homedir or adding the following to the dependencies in your Cargo.toml file.

[dependencies]
homedir = "0.3.4"

Examples

Get the process’ user’s home directory.

use homedir::my_home;
use std::path::PathBuf;

// This assumes that the process' user has "/home/jpetersen" as home directory.
assert_eq!(
    Some(PathBuf::from("/home/jpetersen".to_owned())),
    my_home()?
);

Get an arbitrary user’s home directory.

use homedir::home;
use std::path::PathBuf;

// This assumes there is a user named `Administrator` which has
// `C:\Users\Administrator` as a home directory.
assert_eq!(
    Some(PathBuf::from("C:\\Users\\Administrator".to_owned())),
    home("Administrator")?
);
assert!(home("NonExistentUser")?.is_none());

Upgrading from 0.2.1 to 0.3

There is a major API restructuring in this version. get_my_home has been renamed to my_home and get_home to home. As well, a cleaner implementation of a cross-platform API has been written, with inspiration taken from the Rust standard library. The UserIdentifier type now has a platform-agnostic implementation of the root of the crate.

This version upgrade removes the wmi and serde dependencies which rendered this crate larger on the Windows version.

For Windows Users

This crate uses the COM library to access the Windows Management Instrumentation for home (not my_home). To use this library, it is required to call CoInitializeEx (or CoInitialize), which has some issues. When using this crate, this will only possibly present an issue to programs that also use the COM library.

Referencing the solution provided in the linked issue, the way that this crate uses the COM library is as follows. It will try to create an instance. If this fails because the COM library is not yet initialized, it will call CoInitializeEx using COINIT_MULTITHREADED, and it will not call CoUninitialize later. This will interfere with libraries that use OleInitialize, which requires COINIT_APARTMENTTHREADED.

To prevent these issues, the feature windows-coinitialize can be used. If it is specified, then the program will call CoInitializeEx if CoCreateInstance fails. It is specified by default. If you opt not to use it, in order to call home, it will be necessary to first call CoInitializeEx with whatever parameters are required, or initialize the other libraries that use it (for example wmi) first.

Finally, this program has been tested on a regular Windows 11 installation. It has not been tested within any Active Directory Windows installation, and the implementation does not test for this or try to account for it in any way. If it does work on these, it will likely return the local profile path of the specified user.

Modules

• unix
  Contains the implementation of the crate for Unix systems.

Structs

• GetHomeError
  This structure contains the error type returned by the functions within this crate.
• UserIdentifier
  This structure represents a user’s identifier.

Functions

• home
  Get the home directory of an arbitrary user. This will return the Err variant if an error occurs. If no user with the given username can be found, Ok(None) is returned instead.
• my_home
  Get the home directory of the process’ current user.